\input macros
\drafttrue
\def\bookline{\CLOS\  Specification}
\def\chapline{Functions in the Programmer Interface}

\beginChapter 2.{Common Lisp Object System Specification}%
{Functions in the Programmer Interface}{Functions in the Programmer Interface}

This document was written by Daniel G. Bobrow, Linda G. DeMichiel,\break
Richard P. Gabriel, Sonya E. Keene, Gregor Kiczales, and David A. Moon.

Contributors to this document include Patrick Dussud, Kenneth Kahn,\break
Jim Kempf, Larry Masinter, Mark Stefik,
Daniel L. Weinreb, and Jon L White.

\endTitlePage

\beginSection{Introduction}

This chapter describes the functions provided by the \CLOS\
Programmer Interface.    The Programmer Interface comprises the set of 
functions and macros that are sufficient for writing most object-oriented
programs.  

The description of each function includes its purpose, its syntax, the
semantics of its arguments and returned values, and often an example
and cross-references to related functions.  This chapter is reference
material that requires an understanding of the basic concepts of the 
Common Lisp Object System.  The functions are arranged in alphabetic 
order for convenient reference.  

It is useful to categorize the functions and macros according to their
role in this standard:

\Vskip 2pc!
\beginlist
\item{\bull}
{Tools used for simple object-oriented programming}

These tools allow for defining new classes, methods, and generic 
functions, and for making instances.   Some tools used within the body
of methods are also listed here.   Some of the macros listed here have 
a corresponding function that performs the same task at a lower level of
abstraction. 

{\bf call-next-method}\hfil\break
{\bf change-class}\hfil\break
{\bf class-changed}\hfil\break
{\bf defclass}\hfil\break
{\bf defgeneric}\hfil\break
{\bf defmethod}\hfil\break
{\bf generic-flet}\hfil\break
{\bf generic-function}\hfil\break
{\bf generic-labels}\hfil\break
{\bf make-instance}\hfil\break
{\bf next-method-p}\hfil\break
{\bf slot-value}\hfil\break
{\bf with-added-methods}\hfil\break
{\bf with-slots}

\vfill\eject
\item{\bull}
{Functions underlying the commonly-used macros}

{\bf add-method}\hfil\break
{\bf ensure-generic-function}\hfil\break
{\bf get-method}\hfil\break
{\bf initialize-instance}\hfil\break
{\bf make-instances-obsolete}\hfil\break
{\bf no-applicable-method}\hfil\break
{\bf remove-method}\hfil\break
{\bf slot-boundp}\hfil\break
{\bf slot-exists-p}\hfil\break
{\bf slot-makunbound}\hfil\break
{\bf slot-missing}\hfil\break
{\bf slot-unbound}\hfil\break
{\bf update-instance-structure}

\item{\bull}
{Tools for declarative method combination}

{\bf define-method-combination}\hfil\break
{\bf invalid-method-error} \hfil\break
{\bf make-method-call}\hfil\break
{\bf method-combination-error}\hfil\break
{\bf method-qualifiers}

\item{\bull}
{General Common Lisp support tools}

{\bf cboundp}\hfil\break
{\bf class-name}\hfil\break
{\bf class-of}\hfil\break
{\bf cmakunbound}\hfil\break
{\bf describe}\hfil\break
{\bf documentation}\hfil\break
{\bf print-object} \hfil\break
{\bf symbol-class}\hfil\break
{\bf symbol-macrolet}

\endlist

\vfill
\endSection%{Introduction}


\beginSection{Notation}

We use an extended Backus Normal Form (BNF) to describe the syntax of
the \OS.  In this description we discuss the syntax of BNF expressions.
The extension we use is as follows:

$$\lbrack\!\lbrack O\,\rbrack\!\rbrack$$

An expression of this form will appear whenever a list of elements is
to be spliced into a larger structure. The symbol $O$ represents
a description of the syntax of some number of syntactic elements to be spliced.
The symbol $O$ must be of the form

$$O\sub 1\ \vert\ \ldots\ \vert\ O\sub n$$

\noindent where each $O\sub i$ can be either of the form $S$ or of
the form $S{\rm *}$.  The expression $\lbrack\!\lbrack
O\,\rbrack\!\rbrack$ means that a list of the form

$$(O\sub{i\sub 1}\ldots O\sub{i\sub j})\quad 1\leq j$$

\noindent is spliced into the enclosing expression where if $n \neq m$
and $1\leq n,m\leq j$,
then either $O\sub{i\sub n}\neq O\sub{i\sub m}$
or $O\sub{i\sub n}$ and $O\sub{i\sub m}$
are each of the form $S{\rm *}$.

For example, the expression

$$(\hbox{{\tt x}}\ {\lbrack\!\lbrack} \hbox{{\tt A}}\ 
 \vert\ \hbox{{\tt B}}{\rm *}\ \vert\ \hbox{{\tt C}}\,
  {\rbrack\!\rbrack}\ \hbox{{\tt y}})$$

\noindent is a description of any of these:

\screen!
(x y)
(x B A C y)
(x A B B B B B C y)
(x C B A B B B y)
\endscreen!

\noindent but not of any of these:

\screen!
(x B B A A C C y)
(x C B C y)
\endscreen!

\endSection


\begincom{add-method}\ftype{Generic Function}

\label Purpose:

The generic function {\bf add-method} adds a method to a generic
function.  It destructively modifies the generic function and returns
the modified generic function as its result.

\label Syntax:

\Defgen {add-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is a generic function
object.

The {\it method\/} argument is a method object.  The lambda-list of
the method function must be congruent with the lambda-lists of any
other methods associated with the generic function and with the
lambda-list of the generic function, or else an error is signaled.

\label Values:

The generic function {\bf add-method} returns the modified generic function.

\label Remarks:

If the given method is already one of the methods of the generic
function or if the method corresponds in parameter specializers and
method qualifiers to an existing method of the generic
function, an error is signaled.

%Note that a given method may be a method on more than one generic
%function.

\label See Also:

{\bf defmethod

defgeneric}

\endcom




\begincom{call-next-method}\ftype{Function}

\label Purpose:

The function {\bf call-next-method} is used within the body of a
method to call the next method.

The function {\bf call-next-method} returns the value or values
returned by the method it calls.  If there is no next method, an error
is signaled.

The type of method combination used determines which 
methods can invoke {\bf call-next-method}.  The standard method
combination type allows {\bf call-next-method} to be used within primary
methods and {\bf :around} methods.  It defines the next method as
follows:

\beginlist
\item{\bull}
If {\bf call-next-method} is used in an {\bf :around} method,
the next method is the next most specific {\bf :around} method, if one is
applicable.

\item{\bull}
If there are no {\bf :around} methods at all or if {\bf
call-next-method} is called by the least specific {\bf :around}
method,  other methods are called as follows:

\itemitem{--} All the {\bf :before} methods are called, in
most specific first order.  Their values are ignored.

\itemitem{--} 
The most specific primary method is called.  Inside the body of a
primary method, {\bf call-next-method} may be used to pass control
to the next most specific primary method.  An error is signaled if {\bf
call-next-method} is used and there is no applicable primary method.

\itemitem{--} All the {\bf :after} methods are called in
most specific last order.  Their values are ignored.

\endlist

\label Syntax:

\Defun {call-next-method} {{\rest} args}

\label Arguments:

When {\bf call-next-method} is called with no arguments, it passes the
current method's original arguments to the next method.  Neither
argument defaulting, nor using {\bf setq}, nor rebinding variables
with the same names as parameters of the method affects the values
{\bf call-next-method} passes to the method it calls.

When {\bf call-next-method} is called with arguments, the next method
is called with those arguments.  When providing arguments to {\bf
call-next-method}, the following rule must be satisfied or an error is
signaled: The set of methods applicable for a changed set of
arguments for {\bf call-next-method} should be the same as the set of
applicable methods for the original arguments to the method, or else
the results are undefined.

If {\bf call-next-method} is called with arguments but omits
optional arguments, the next method defaults those arguments.
Optimizations of the error checking are possible but they should be
invisible to the programmer.

\label Values:

The function {\bf call-next-method} returns the value or values
returned by the method it calls.  

\label Remarks:

Further computation is possible after {\bf call-next-method} returns.

The function {\bf call-next-method} has dynamic extent within the
method within which it is referenced.  Implementations may extend {\bf
call-next-method} to have indefinite extent.  All portable programs
must treat as undefined the invocation of {\bf call-next-method}
outside a generic function.

For generic functions using a type of method combination defined by
the short form of {\bf define-method-combination}, {\bf
call-next-method} can be used in {\bf :around} methods only.

The function {\bf next-method-p} can be used to test whether there is
a next method.

If {\bf call-next-method} is used in methods that do not support it,
an error is signaled.

\label See Also:

``Method Selection and Combination''

``Standard Method Combination'' 

{\bf define-method-combination}

{\bf next-method-p}

\endcom


\begincom{cboundp}\ftype{Function}

\label Purpose:

The function {\bf cboundp} tests whether the given symbol is
associated with a class.

\label Syntax:

\Defun {cboundp} {symbol {\opt} environment}

\label Arguments:

The optional {\it environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

\label Values:

The function {\bf cboundp} returns true or false.

\label See Also:

{\bf symbol-class

cmakunbound}

\endcom



\begincom{change-class}\ftype{Function}

\label Purpose:

The function {\bf change-class} changes the class of an instance to a
new class.  It destructively modifies and returns the instance.  The
values of local slots held in common between the old and new class are
preserved in the new instance.  The other slots are initialized as
described in the section ``Changing Classes.''  

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument is a Lisp object, although 
not all objects are required to allow {\bf change-class}.

The {\it new-class\/} argument is a class object or a symbol that names
a class. 

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

(defclass position () ())

(defclass x-y-position (position)
    ((x :initform 0)
     (y :initform 0)))

(defclass rho-theta-position (position)
    ((rho :initform 0)
     (theta :initform 0)))

(defmethod class-changed ((old x-y-position) 
                          (new rho-theta-position))
  ;; Copy the position information from old to new to make new
  ;; be a rho-theta-position at the same position as old.
  (let ((x (position-x old))
        (y (position-y old)))
    (setf (position-rho new) (atan y x)
          (position-theta new) (sqrt (+ (* x x) (* y y))))))

;;; At this point an instance of the class x-y-position can be
;;; changed to be an instance of the class rho-theta-position using
;;; change-class:

(setq p1 (make-instance 'x-y-position :x 2 :y 0))

(change-class p1 'rho-theta-position)

;;; The result is that the instance bound to p1 is now an instance of
;;; the class rho-theta-position.   The method for class-changed
;;; performed the initializion of the rho and theta slots based
;;; on the value of the x and y slots, which were maintained by
;;; the old instance.

\endscreen!

\label Remarks:

The \OS\ requires {\bf change-class} to apply in only the following case:
let $C\sub 1$ and $C\sub 2$ be classes that are defined by {\bf
defclass} without using the {\bf :metaclass} option in either case; let
$X$ be an instance of $C\sub 1$. Then, the class of $X$ can be changed
from $C\sub 1$ to $C\sub 2$.  Both before and after the call to {\bf
change-class}, the metaclass of $X$ is the default metaclass, namely
{\bf standard-class}.

Implementors can choose to support {\bf change-class} in additional
cases.  For example, this standard does not require that
{\bf change-class} be able to accept an instance of a standard type class
as its first argument or a standard type class as its second argument;
however, it is valid for an implementation to support this for some
standard type classes.

If {\bf change-class} is applied to arguments that are not supported by
the implementation, an error is signaled.

After completing all other actions, {\bf change-class} invokes the generic
function {\bf class-changed}.  The generic function {\bf class-changed}
can be used to reinitialize slots.

The function {\bf change-class} has several semantic difficulties.
First, it performs a destructive operation that can be invoked within a
method on an instance that was used to select that method. When multiple
methods are involved because methods are being combined, the problem
could be compounded. Second, some implementations might use compiler
optimizations of slot access and when the class of an instance is
changed, the assumptions the compiler made might be violated.
This implies that an application programmer must not use {\bf
change-class} inside a method if any methods for that generic function 
access any slots, or else the results are undefined.

\eject
\label See Also:
 
``Redefining Classes''

{\bf class-changed}

\endcom




\begincom{class-changed}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-changed} is not intended to be called
by programmers.  Programmers are expected to write methods for it.
The function {\bf class-changed} is called only by the function {\bf
change-class}.  

\label Syntax:

\Defgen {class-changed} {previous current}

\label Arguments:

When {\bf change-class} is invoked on an instance, a copy of that instance
is made; {\bf change-class} then destructively alters the original instance.
The first argument to {\bf class-changed}, {\it previous\/}, is that copy,
and the second argument, {\it current}, is the altered original instance.

The typical use of {\it previous\/} is to extract old slot values by using
{\bf slot-value} or {\bf with-slots} or by invoking an accessor generic
function.

\label Values:

The value returned by {\bf class-changed} is ignored by {\bf change-class}.

\label Examples:

See the example for the function {\bf change-class}.

\label Remarks:

The arguments to {\bf class-changed} are computed by {\bf
change-class}.  The first argument is an instance of the original
class created to hold the old slot values temporarily.  This argument
has dynamic extent within {\bf class-changed}; if it is
referenced in any way once {\bf class-changed} returns, the results are
undefined.

The default method for {\bf class-changed} does nothing.  Methods on
{\bf class-changed} can be defined to initialize slots differently from
{\bf change-class}.   In this
way {\bf class-changed} methods can alter the default behavior of {\bf
change-class} with respect to slot value preservation.  The default
behavior is described in ``Changing Classes.''

The generic function {\bf class-changed} uses standard method 
combination; thus {\bf :before}, {\bf :after}, {\bf :around}, and
unqualified methods are allowed. 

\eject
\label See Also:

``Changing Classes''

{\bf change-class

add-method

make-method}

\endcom



\begincom{class-name}\ftype{Generic Function}

\label Purpose:

The generic function {\bf class-name} takes a class object and returns its
name.

\label Syntax:

\Defgen {class-name} {class}

\label Arguments:

The {\it class\/} argument is a class object.

\label Values:

The name of the given class is returned as the result.

\label Remarks:

The name of an anonymous class is {\bf nil}.

\label See Also:

{\bf symbol-class}

\endcom



\begincom{class-of}\ftype{Function}

\label Purpose:

The function {\bf class-of} returns the class object for the most
specific class of which the given object is an instance.  Every Common
Lisp object has a class.

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:

The function {\bf class-of} returns the class object that represents the
most specific class of which the  argument is an instance. 

\label Remarks:

The Common Lisp types that have corresponding classes are listed in
Figure~1-1.

%If the object was created with a constructor defined by {\bf defstruct}, 
%the class that is returned is the class with the same name as the data
%type defined with the {\bf defstruct} form.

%If the object is an instance of a class whose class is {\bf
%standard-type-class} or a subclass of {\bf standard-type-class} (other 
%than a class created with {\bf defstruct}), the class that is returned
%is the most specific class according to Figure~1-2.

\endcom


\begincom{cmakunbound}\ftype{Function}

\label Purpose:

The function {\bf cmakunbound} removes any association from the given symbol
to a class.

\label Syntax:

\Defun {cmakunbound} {symbol {\opt} environment}

\label Arguments:

The optional {\it environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

\label Values:

The given symbol is returned.

\label See Also:

{\bf symbol-class

cboundp}

\endcom



\begincom{defclass}\ftype{Macro}

\label Purpose:

The macro {\bf defclass} defines a new class.  It returns the new class
object as its result.

The syntax of {\bf defclass} provides options for specifying default
initialization values for slots, for requesting that methods for
appropriately named generic functions be automatically generated for
reading and writing the values of slots, and for requesting that a
constructor function be automatically generated for making instances of
the new class.  No accessors, readers, or constructor functions are defined
by default; their generation must be explicitly requested.

Defining a new class also causes a type of the same name to be
defined.  The predicate {\tt (typep {\it object class-name\/})} is
true if the class of the given object is {\it class-name\/} itself or
a subclass of the class {\it class-name}.  A class object can be used
as a type specifier.  Thus {\tt (typep {\it object class\/})} is true
if the class of the {\it object\/} is {\it class\/} itself or a
subclass of {\it class}.

\eject
\label Syntax:

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name} \paren{\star{\curly{superclass-name}}}
\paren{\star{\curly{slot-spec}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it superclass-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-spec\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \star{\curly{slot-option}})\cr
\Vskip 1pc!
\+&{\it slot-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :accessor} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :reader} {\it generic-function-name\/} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type\/} $\vert$ \cr
\+&&{\tt :initarg} {\it name\/} $\vert$ \cr
\+&&{\tt :initform} {\it form\/} $\vert$ \cr
\+&&{\tt :type} {\it type-specifier\/} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :constructor} {\it symbol\/} \brac{boa-arglist\/}) $\vert$\cr
\+&&({\tt :default-initargs} {\it initarg-list\/}) $\vert$ \cr
\+&&({\tt :documentation} {\it string\/}) $\vert$ \cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform}{\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
\Vskip 1pc!
\+&{\it initarg-list\/}::$=$ \star{\curly{\it initarg-name default-value-form}} \cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject


\label Arguments:

The {\it class-name\/} argument is a non-{\bf nil} symbol.  It becomes the 
name of the new class.  If a class with the same name already exists, the
definition of that class is replaced.

Each {\it superclass-name\/} argument is a non-{\bf nil} symbol.  The
new class will inherit slots and methods from each of its
superclasses, from their superclasses, and so on.  See the section
``Inheritance'' for a discussion of how slots and methods are
inherited.

Each {\it slot-spec\/} argument is the name of the slot or a list consisting
of the slot name followed by zero or more slot options.  The {\it slot-name\/}
argument is a symbol that can be used as a Common Lisp variable name.   
If there are any duplicate slot names, an error is signaled. 

The following slot options are available:

\beginlist

\item{\bull} 
The {\bf :accessor} option specifies that an unqualified method
is to be defined on the generic function named {\it
generic-function-name\/} to read the value of the given slot and that
an unqualified method is to be defined on the setf generic function named
{\it generic-function-name} to be used with {\bf setf} to modify the
value of the slot.  The {\it generic-function-name\/} argument is a
non-{\bf nil} symbol.  The {\bf :accessor} option may be specified
more than once for a given slot.

\item{\bull}
The {\bf :reader} option specifies that an unqualified method
is to be defined on the generic function named {\it
generic-function-name\/} to read the value of the given slot.  The
{\it generic-function-name\/} argument is a non-{\bf nil} symbol.  The
{\bf :reader} option may be specified more than once for a given slot.

\item{\bull} 
The {\bf :allocation} option is used to specify where storage is to be
allocated for the given slot.  Storage for a slot may be located in
each instance or in the class object itself.  The value of the {\it
allocation-type\/} argument can be one of the following keywords: {\bf
:instance} or {\bf :class}.  The {\bf :allocation} option may be
specified once at most for a given slot.  If the {\bf :allocation}
option is not specified, a local slot of the given name is allocated
in each instance of the class.

\itemitem{--}
If {\it allocation-type\/} is {\bf :instance}, a local slot of the given name
is allocated in each instance of the class.  

\itemitem{--}
If {\it allocation-type\/} is {\bf :class}, a shared slot of the given
name is allocated in the class object created by this {\bf defclass}
form.  The value of the slot is shared by all instances of the class.
Any subclass of this class will share this single slot unless the {\bf
defclass} form for that subclass specifies a slot of the same name.

\item{\bull}
The {\bf :initarg} slot option declares an initialization argument
named {\it name\/} and specifies that this initialization argument
initializes the given slot.  If the initialization argument has a
value, the value will be stored into the given slot and the slot's
{\bf :initform} argument, if any, is not evaluated.  If none of the
initialization arguments specified for a given slot has a value, the
slot is initialized according to the {\bf :initform} argument, if
specified.  The {\bf :initarg} slot option can be specified more than
once for a given slot.  The {\it name\/} argument is any symbol.

\vfill\eject
\item{\bull} The {\bf :initform} option is used to provide a default
initial value form to be used in the initialization of the slot.  The
{\bf :initform} option may be specified once at most for a given slot.
This form is evaluated every time it is used.  The lexical environment
in which this form is evaluated is the lexical environment in which
{\bf defclass} was evaluated.  Note that the lexical environment
refers both to variables and to functions.  The dynamic environment is
the one in effect at the time the form is evaluated.  This is the same
behavior specified for {\bf defstruct} slot initialization forms in
{\it Common Lisp: The Language}.

The syntax {\tt ({\it slotname form\/})} is not allowed as an
abbreviation for {\tt ({\it slotname\/} :initform {\it form\/})}.

\item{\bull}
The {\bf :type} option specifies the type of the slot contents.
This specifies that the contents of the slot will always
be of the specified data type.  It effectively declares the result
type of the reader generic function when applied to an object of this
class.  An implementation may or may not choose to check the type of
the new value when initializing or assigning to a slot.  The
expression {\tt ({\tt typep} {\it value type-specifier\/})} will be
true for the value stored in the slot.  The {\bf :type} option may be
specified once at most for a given slot.  The {\bf :type} option is
further discussed in the section ``Inheritance of Slots and Slot Options.''

\endlist

Each class option is an option that refers to the class as a whole
or to all class slots.  The following class options are available:

\beginlist
\item{\bull}
The {\bf :constructor} option causes a constructor function to be
generated automatically.  The constructor function is used to make new
instances of the class.  The {\it symbol\/} argument is a non-{\bf
nil} symbol that specifies the name of the constructor function.  If
the {\it boa-arglist\/} argument is present, it describes the
arguments to the constructor.  The {\it boa-arglist\/} argument of
{\bf defclass} is the same as that of {\bf defstruct}.  The {\bf
:constructor} option may be specified more than once.

\item{\bull}
The {\bf :default-initargs} option is followed by a list of
alternating initialization argument names and default initialization
argument forms.  If any of these initialization arguments does not
appear in the initialization argument list supplied to {\bf
make-instance}, the corresponding default initialization argument form
is evaluated, and the initialization argument name and the form's
value are added to the end of the initialization argument list.  The
default initialization argument form is evaluated each time it is
used.  The lexical environment in which this form is evaluated is the
lexical environment in which the {\bf defclass} form was evaluated.
The dynamic environment is the dynamic environment in which {\bf
make-instance} was called.  The {\bf :default-initargs} option can be
specified more than once.  An error is signaled, however, if an
initialization argument name appears more than once in a single {\bf
:default-initargs} option or in more than one {\bf :default-initargs}
option for a single class.

\item{\bull} 
The {\bf :documentation} option causes a documentation string to be
attached to the class name.  The documentation type for this string is
{\bf type}.  The form {\tt (documentation {\it class-name\/} 'type)}
may be used to retrieve the documentation string.  The {\bf
:documentation} option may be specified once at most.

\vfill\eject
\item{\bull}
The {\bf :metaclass} option is used to specify that instances of the
class being defined are to have a different metaclass than the default
provided by the system (the class {\bf standard-class}).  The {\it
class-name} argument is the name of the desired metaclass.  The {\bf
:metaclass} option may be specified once at most.

\endlist

\label Values:

The new class object is returned as the result.

\label Remarks:

If a class of the same name already exists, that class is redefined
and instances of the class (and subclasses of it) are updated to the
new definition at the time that they are next accessed.  For details,
see ``Redefining Classes'' and {\bf change-class}.  Redefining a
standard type class is not allowed.

Note the following rules of {\bf defclass}:

\beginlist

\item{\bull}
It is not required that the superclasses of a class be defined before
the {\bf defclass} form for that class is evaluated.

\item{\bull}
All the superclasses of a class must be defined before 
an instance of the class can be made.

\item{\bull}
A class must be defined before it can be used as a parameter
specializer in a {\bf defmethod} form.

\item{\bull}
All the superclasses of a class must be defined before
a {\bf with-slots} form that uses that class can be evaluated.

\endlist

The behavior of the \OS\ can be extended in cases where these rules are not
obeyed.

Some slot options are inherited by a class from its 
superclasses, and some can be shadowed or altered by providing a
local slot description.   No class options are inherited.  For a 
detailed description of how slots and slot options are inherited,
see the section ``Inheritance of Slots and Slot Options.'' 

Some implementations might add other options to {\bf defclass}.
Therefore, it is required that all implementations signal an error if
they observe a class option or a slot option that is not implemented
locally.

If no default value for a slot is specified in either a {\bf
defclass} or a {\bf make-instance} form, the initial value of the
slot is unspecified.  If an uninitialized slot is read, the
generic function {\bf slot-unbound} is called.  The default method
on {\bf slot-unbound} signals an error.

It is valid to specify more than one accessor or reader for a slot.
No other slot option may appear more than once in a single slot
description.

The {\bf :constructor} class option may appear more than once.  No
other class option may appear more than once in a single {\bf
defclass} form.

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value}.

\label See Also:

{\bf slot-value}

``Classes''

``Inheritance''

``Redefining Classes''

``Determining the Class Precedence List''

\endcom



\begincom{defgeneric}\ftype{Macro}

\label Purpose:

The macro {\bf defgeneric} is used to define a generic function or to
specify options and declarations that pertain to a generic function as
a whole.

The generic function is stored in the function cell of the symbol {\it name}.
If {\tt (fboundp {\it name\/})} is {\bf nil}, a new generic function 
is created.  If {\tt (symbol-function {\it name\/})} is a generic function,
that generic function is modified.  If neither of these conditions holds,
{\bf defgeneric} signals an error.

Each {\it method-description\/} defines a method on the generic function.
The lambda-list of each method must be congruent with the lambda-list
specified by the {\it lambda-list\/} option.  If this condition
does not hold, an error is signaled.  See the section ``Congruent
Lambda-lists for All Methods of a Generic Function'' for a definition
of congruence in this context.

The macro {\bf defgeneric} may also be used to define a setf generic
function.  A setf generic function is called in an expression such as
{\tt (setf ({\it name arguments\/}) new-value)}.
If {\tt (fboundp (setf {\it name\/}))} is {\bf nil}, a new generic
function is created.  If {\tt (symbol-function (setf {\it name\/}))}
is a generic function, that generic function is modified.  If neither
of these conditions holds, {\bf defgeneric} signals an error.

The macro {\bf defgeneric} returns the generic function object 
as its result.

\label Syntax:

\Defmac {defgeneric} {\vtop{\hbox{\curly{\curly{name lambda-list\/} $\vert$ \curly{{\tt (setf {\it name\/})} setf-lambda-list\/}}}
%\hbox{\star{\curly{option $\vert$ method-description\/}}}}}
\hbox{$\lbrack\!\lbrack$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$}}}

{\it name\/}::$=$ {\it symbol}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it setf-lambda-list\/}::$=$ (& {\it setf-var\/} \star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
{\it setf-var\/}::$=$ {\it var}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order \plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method {\it method-specifier\/})}
\Vskip 1pc!
{\it method-specifier\/}::$=$ \vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}}}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it non-nil-atom}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var parameter-specializer-name\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\settabs\+\hskip\leftskip&\cr
\Vskip1pc!\null
\+&{\it parameter-specializer-name\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt eql} {\it object}{\rm )}\cr
\Vskip 1pc!

\eject
\label Arguments:

The {\it name} argument is a non-{\bf nil} symbol.

The {\it lambda-list\/} argument is an ordinary function lambda-list
with these exceptions:

\beginlist
\item{\bull}
No {\bf \&aux} variables are allowed. 

\item{\bull}
Optional and keyword arguments may not have default initial value forms
nor use supplied-p parameters.
The generic function passes to the method all the argument values passed to
it, and only those; default values are not supported.
Note that optional and keyword arguments in method definitions, however,
can have default initial value forms and can use supplied-p parameters. 
\endlist

The {\it setf-lambda-list\/} argument is an extension of the
lambda-list described above, in which the first required parameter
receives the {\it new-value\/} argument to {\bf setf} when a setf
generic function is invoked.

The following options are provided.  A given option may occur only once.

\beginlist
 
\item{\bull} 
The {\bf :argument-precedence-order} option is used to specify the
order in which the required arguments in a call to the generic
function are tested for specificity when selecting a particular
method.  By default, all required arguments are considered from left
to right; each required argument has precedence over those to its
right.  Each required argument must be included exactly once as a {\it
parameter-name} so that the full and unambiguous precedence order is
supplied.  If this condition is not met, an error is signaled.

\item{\bull}
The {\bf declare} option is used to specify declarations that pertain
to the generic function.  The following standard Common Lisp
declaration is allowed:

\itemitem{--}
An {\bf optimize} declaration specifies whether method selection
should be optimized for speed or space, but it has no effect on methods.
To control how a method is optimized, an {\bf optimize} declaration
must be placed directly in the {\bf defmethod} form.  The optimization
qualities {\bf speed} and {\bf space} are the only qualities this
standard requires, but other qualities may be recognized by particular
implementations.  A simple implementation that has only one method
selection technique and ignores the {\bf optimize} declaration is
valid.

\item{}
The {\bf special}, {\bf ftype}, {\bf function}, {\bf inline}, {\bf
notinline}, and {\bf declaration} declarations are not permitted.
Individual implementations can support their own additional
declarations.  If an implementation notices a declaration that it does
not support and that has not been proclaimed as a nonstandard
declaration name, it should issue a warning.

\item{\bull} 
The {\bf :documentation} argument associates a documentation string
with the generic function.  The documentation type for this string is
{\bf function}.  The form {\tt (documentation {\it
generic-function-name\/} 'function)} may be used to retrieve this
string.
\vfill\eject
\item{\bull} 
The {\bf :generic-function-class} option may be used to specify that
the generic function is to have a different class than the default
provided by the system (the class {\bf standard-generic-function}).
The {\it class-name\/} argument is the name of a class that can be the
class of a generic function.

\item{\bull} 
The {\bf :method-class} option is used to specify that all methods for
this generic function are to have a different class than the default
provided by the system (the class {\bf standard-method}).  The {\it
class-name\/} argument is the name of a class that is capable of being
the class of a method.

\item{\bull} 
The {\bf :method-combination} option is followed by a symbol that
names a type of method combination.  The arguments (if any) that
follow that symbol depend on the type of method combination.  Note
that the standard method combination type does not support any
arguments.  However, all types of method combination defined by the
short form of {\bf define-method-combination} accept an optional
argument named {\it order\/}, defaulting to {\bf
:most-specific-first}, where a value of {\bf :most-specific-last} reverses
the order of the primary methods, without affecting the order of the
auxiliary methods.

\endlist

The {\it method-description\/} arguments define the methods that are
to be added to the generic function.
The {\it method-qualifier}, {\it specialized-lambda-list}, and {\it
specialized-setf-lambda-list\/} arguments in a method description
are the same as for {\bf defmethod}.

\beginlist

\item{\bull}
Each {\it method qualifier\/} argument is an object that is used by
method combination to identify the given method.  A method qualifier
is a non-{\bf nil} atom.  The method combination type may further
restrict what a method qualifier may be.  The standard method
combination type allows for unqualified methods or methods whose sole
qualifier is one of the following keywords: {\bf :before}, {\bf
:after}, or {\bf :around}.

\item{\bull}
The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda-list except that the names of required parameters can
be replaced by specialized parameters.  A specialized parameter is a
list of the form {\tt ({\it variable-name 
parameter-specializer-name\/})}.  Only required parameters may be
specialized.  A parameter specializer name is a symbol that names a 
user-defined class, a structure defined by {\bf defstruct} if the {\bf
:type} option was not used, or a class that corresponds to a Common 
Lisp type specifier.  Note that not all Common Lisp types have a
corresponding class.  A parameter specializer name can also be {\tt
(eql {\it object\/})}.  Such a parameter specializer name indicates
that the corresponding argument must be {\bf eql} to the object
for the method to be applicable.  If no parameter specializer name is
specified for a given required parameter, the parameter specializer
name for that parameter defaults to {\bf t}.  A method whose required
parameters all have {\bf t} parameter specializers is termed a {\bit
default method}.  Such a method is selected when no more specific
method for the generic function is applicable.  See the section
``Introduction to Methods'' for further discussion.

For a setf generic function, the first required parameter of the generic
function lambda list receives the {\it new-value\/} argument to {\bf setf}
when the setf method is invoked. 

\item{\bull}
Each {\it form\/} is evaluated within an implicit {\bf progn} as the
body of the method.

\endlist

\label Values:

The generic function object is returned as the result. 

\label Remarks:

If a method already exists on the given generic function with the same 
parameter specializers and the same qualifiers, {\bf defgeneric} replaces
the existing method with the one now being defined. 

If no method descriptions are specified and a generic function of the same
name does not already exist, a anonymous generic function with no
methods is created.

The {\it lambda-list\/} and {\it setf-lambda-list\/} argument of {\bf
defgeneric} specifies the shape of lambda-lists for the methods of
this generic function.  All methods for the generic function must have
lambda-lists that are congruent with this shape.  If a {\bf
defgeneric} form is evaluated and some methods for that generic
function have lambda-lists that are not congruent with that given in
the {\bf defgeneric} form, an error is signaled.  For further details
on method congruence, see ``Congruent Lambda-lists for all Methods of
a Generic Function''

Some implementations might add other options to {\bf defgeneric}. 
Therefore, it is required that all implementations signal an error if
they observe an option that is not implemented locally.

The macro {\bf defgeneric} is implemented in terms of {\bf
ensure-generic-function} followed by zero or more invocations of {\bf
defmethod}.

\label See Also:

``Congruent Lambda-lists for All Methods of a Generic Function'' 

{\bf defmethod

ensure-generic-function

generic-function}

\endcom




\begincom{define-method-combination}\ftype{Macro}

\label Purpose:

The macro {\bf define-method-combination} is used to define new types
of method combination.

There are two forms of {\bf define-method-combination}.  The short
form is a simple facility for the cases that have been found
to be most commonly needed.  The long form is more powerful but more
verbose.  It resembles {\bf defmacro} in that the body is an
expression, usually using backquote, that computes a Lisp form.  Thus
arbitrary control structures can be implemented.  The long form also
allows arbitrary processing of method qualifiers.

\label Syntax:

\Defmac {define-method-combination} {name \star{\curly{short-form-option}}}
\Vskip 1pc!
{\it short-form-option\/}::$=$ {\tt\vtop{\hbox{:documentation {\it string\/} $\vert$}
\hbox{:identity-with-one-argument {\it boolean\/} $\vert$}
\hbox{:operator {\it operator\/} $\vert$}}}
\Vskip1pc!

\Defmac {define-method-combination} {\vtop{\hbox{name lambda-list }
\hbox{\paren{\star{\curly{method-group-specifier}}} }
\hbox{\star{\curly {declaration $\vert$ doc-string}}}
\hbox{\star{\curly{form}}}}}
\vbox
{\halign {\hskip \leftskip#\hfil&#\hfil\cr
{\it method-group-specifier\/}::$=$ (&{\it variable\/}
\curly{\plus{\curly{qualifier-pattern}} $\vert$ predicate}\cr
&\star{\curly{long-form-option}})\cr}}
\Vskip 1pc!
{\it long-form-option\/}::$=$ {\tt\vtop{\hbox{:description {\it format-string\/} $\vert$}
\hbox{:order {\it order\/} $\vert$}
\hbox{:required {\it boolean\/}}}}
\Vskip1pc!\null

\label Arguments:

In both the short and long forms, {\it name\/} is a symbol.  By convention,
non-keyword, non-{\bf nil} symbols are usually used.

\label Arguments of the Short Form:

The short form syntax of {\bf define-method-combination} is recognized
when the second subform is a non-{\bf nil} symbol or is not present.
When the short form is used, {\it name\/} is defined as a type of
method combination that produces a Lisp form {\tt ({\it operator
method-call method-call $\ldots$ })}.  The {\it operator\/} is a symbol
that can be the name of a function, macro, or special form.  The
{\it operator\/} can be specified by a keyword option; it defaults to {\it
name}.

Keyword options for the short form are the following:

\beginlist

\item{\bull}
The {\bf :documentation} option is used to document the method-combination type.

\item{\bull}
The {\bf :identity-with-one-argument} option enables an optimization
when {\it boolean\/} is true (the default is false).  If there is
exactly one applicable method and it is a primary method, that method
serves as the effective method and {\it operator\/} is not called.
This optimization avoids the need to create a new effective method and
avoids the overhead of a function call.  This option is designed to be
used with operators such as {\bf progn}, {\bf and}, {\bf $+$}, and
{\bf max}.

\item{\bull}
The {\bf :operator} option specifies the name of the operator.  The
{\it operator\/} argument is a symbol that can be the name of a
function, macro, or special form.  By convention, {\it name\/} and
{\it operator\/} are often the same symbol, but this is not required.

\endlist

None of the subforms is evaluated.

These types of method combination require exactly one qualifier per
method.  An error is signaled if there are applicable methods with no
qualifiers, or with qualifiers that are not supported by the method
combination type. 

A method combination procedure defined in this way recognizes two
roles for methods.  A method whose one qualifier is the symbol naming
this type of method combination is defined to be a primary method.  At
least one primary method must be applicable or an error is signaled.
A method with {\bf :around} as its one qualifier is an auxiliary
method that behaves the same as a {\bf :around} method in standard
method combination.  The function {\bf call-next-method} can only be
used in {\bf :around} methods, not in primary methods defined by the
{\bf define-method-combination} macro.

A method combination procedure defined in this way accepts an optional
argument named {\it order}, which defaults to {\bf
:most-specific-first}.  A value of {\bf :most-specific-last} reverses
the order of the primary methods without affecting the order of the
auxiliary methods.

A large fraction of the types of method combination needed by 
most programmers can be implemented with this short form, which is 
provided for convenience.   The short form automatically includes 
error checking and support for {\bf :around} methods
and avoids the need for the use of the backquote and comma.

\eject
\label Arguments of the Long Form:

The long form syntax of {\bf define-method-combination} is recognized 
when the second subform is a list.  

The {\it lambda-list\/} argument is an ordinary lambda-list.  It
receives any arguments provided after the name of the method
combination type in the {\bf :method-combination} option to {\bf
defgeneric}.

A list of method-group specifiers follows.  Each specifier selects a subset
of the applicable methods to play a particular role, either by matching
their qualifiers against some patterns or by testing their qualifiers with
a predicate.   These method-group specifiers define all method qualifiers
that can be used with this type of method combination.  If an applicable 
method does not fall into any method-group, the system signals the error
that the method is invalid for the kind of method combination in use.

Each method-group specifier names a variable.  During the execution of
the forms in the body of {\bf define-method-combination}, this
variable is bound to a list of the methods in the method-group.  The
methods in this list occur in most-specific-first order.

A qualifier pattern is a list or the symbol {\bf *}.  A method matches
a qualifier pattern if the method's list of qualifiers is {\bf equal}
to the qualifier pattern (except that the symbol {\bf *} in a qualifier
pattern matches anything).  Thus, a qualifier pattern can be one of the
following: the empty list {\bf ()}, which matches unqualified methods;
the symbol {\bf *}, which matches all methods; a true list, which
matches methods with the same number of qualifiers as the length of
the list when each qualifier matches the corresponding list element;
or a dotted list that ends in the symbol {\bf *} (the {\bf *} matches
any number of additional qualifiers).


Each applicable method is tested against the qualifier patterns and
predicates in left-to-right order.  As soon as a qualifier pattern matches
or a predicate returns true, the method becomes a member of the
corresponding method-group and no further tests are made.  Thus, if a method
could be a member of more than one method-group, it joins only the first
such group.  If a method-group has more than one qualifier pattern, a
method need only satisfy one of the qualifier patterns to be a member of
the group.

The name of a predicate function can appear instead of qualifier
patterns in a method-group specifier.  The predicate is called for
each method that has not been assigned to an earlier method-group; it
is called with one argument, the method's qualifier list.  The
predicate should return true if the method is to be a member of the
method-group.  A predicate can be distinguished from a qualifier pattern
because it is a symbol other than {\bf nil} or {\bf *}.

Method-group specifiers can have keyword options following the
qualifier patterns or predicate.  Keyword options can be distinguished from
additional qualifier patterns because they are neither lists nor the symbol
{\bf *}.  The keyword options are as follows:

\beginlist

\item{\bull}
The {\bf :description} option is used to provide a description of the
role of methods in the method-group.  Programming environment tools
use {\tt (apply \#'format stream {\it format-string\/}
(method-qualifiers {\it method\/}))} to print this description, which
is expected to be concise, that is, one or two words.  This keyword
option allows the description of a method qualifier to be defined in
the same module that defines the semantic meaning of the method
qualifier.  In most cases, {\it format-string\/} will not contain any
format directives, but they are available for generality.  If {\bf
:description} is not specified, a default description is generated
based on the variable name and the qualifier patterns and on whether
this method-group includes the unqualified methods.  The argument {\it
format-string\/} is not evaluated.

\item{\bull}
The {\bf :order} option specifies the order of methods.  The {\it
order\/} argument is a form that evaluates to {\bf
:most-specific-first} or {\bf :most-specific-last}.  If it evaluates
to any other value, an error is signaled.  This keyword option is a
convenience and does not add any expressive power.
If {\bf :order} is not specified, it defaults to {\bf :most-specific-first}.

\item{\bull}
The {\bf :required} option specifies whether at least one method in
this method-group is required.  If the {\it boolean\/} argument is
non-{\bf nil} and the method-group is empty (that is, no applicable
methods match the qualifier patterns or satisfy the predicate), an
error is signaled.  This keyword option is a convenience and does not
add any expressive power.  If {\bf :required} is not specified,
it defaults to {\bf nil}.  The {\it boolean\/} argument is not
evaluated.

\endlist

The use of method-group specifiers provides a convenient syntax to
select methods, to divide them among the possible roles, and to perform the
necessary error checking.  It is possible to perform further filtering
of methods in the body forms by using normal list-processing operations
and the functions {\bf method-qualifiers} and {\bf
invalid-method-error}.  It is permissible to use {\bf setq} on the
variables named in the method-group specifiers and to bind additional
variables.  It is also possible to bypass the method-group specifier
mechanism and do everything in the body forms.  This is accomplished
by writing a single method group with {\bf *} as its only qualifier
pattern; the variable is then bound to a list of all of the applicable
methods, in most specific first order.

The body {\it forms\/} compute and return the Lisp form that specifies how
the methods are combined, that is, the effective method.
The body of {\bf define-method-combination} resembles the body of
{\bf defmacro} and uses backquote in a similar way.
The function {\bf make-method-call} is also used in constructing the
Lisp form; it hides the implementation-dependent details of how
methods are called.  Programmers always use {\bf make-method-call} to
translate from the lists of method objects produced by the method-group
specifiers to Lisp forms that invoke those methods.
 
Erroneous conditions detected by the body should be reported with
{\bf method-combination-error} or {\bf invalid-method-error}; these functions
add any necessary contextual information to the error message and will
signal the appropriate error.

The body {\it forms\/} are evaluated inside of the bindings created by the
lambda-list and method-group specifiers.  Declarations at the head of
the body are positioned directly inside of bindings created by the
lambda-list and outside of the bindings of the method-group variables. 
Thus method-group variables cannot be declared.

Within the body {\it forms\/}, the lexical variable {\bf generic-function}
is bound to the generic-function object.

If a {\it doc-string\/} argument is present, it documents the
method-combination type.

\vfill\eject
The functions {\bf make-method-call}, {\bf method-combination-error}, and
{\bf invalid-method-error} can be called from the body {\it forms\/} or
from functions called by the body {\it forms\/}.  The action of these three
functions can depend on dynamic variables automatically bound before
the method combination function is called.  These variables might contain the
parameter list of the effective method or other implementation-dependent
information.

Note that two methods with identical specializers, but different
qualifiers, are not ordered by the algorithm described in Step 2 of
the method selection and combination process described in the section
``Method Selection and Combination.''  Normally the two methods play
different roles in the effective method because they have different
qualifiers, and no matter how they are ordered in the result of Step
2, the effective method is the same.  If the two methods play the same
role and their order matters, an error is signaled.  This happens as
part of the qualifier pattern matching in {\bf
define-method-combination}.

\label Values:

The value returned by the {\bf define-method-combination} macro is the name of
the new type of method combination.

\label Examples:

Most examples of the long form of {\bf define-method-combination} also
illustrate the use of the related functions that are provided as part
of the declarative method combination facility.

\screen!
;;; Examples of the short form of define-method-combination

(define-method-combination and :identity-with-one-argument t) 

(defmethod func and ((x class1) y) ...)

;;; The equivalent of this example in the long form is:

(define-method-combination and 
        (&optional (order ':most-specific-first))
        ((around (:around))
         (primary (and) :order order :required t))
  (make-method-call `(,@around
                      ,(make-method-call primary
                                         :operator 'and
                                         :identity-with-one-argument t))
                    :operator :call-next-method))

;;; Examples of the long form of define-method-combination

;The default method-combination technique
(define-method-combination standard ()
        ((around (:around))
         (before (:before))
         (primary () :required t)
         (after (:after)))
  (make-method-call `(,@around
                      (multiple-value-prog1
			(progn
                         ,(make-method-call before)
                         ,(make-method-call primary
                                            :operator :call-next-method))
                        ,(make-method-call (reverse after))))
                    :operator :call-next-method))

;A simple way to try several methods until one returns non-nil
(define-method-combination and ()
        ((methods () (and)))
  (make-method-call methods :operator 'and))

;A more complete version of the preceding
(define-method-combination and 
        (&optional (order ':most-specific-first))
        ((around (:around))
         (primary (and)))
  ;; Process the order argument
  (case order
    (:most-specific-first)
    (:most-specific-last (setq primary (reverse primary)))
    (otherwise (method-combination-error "~S is an invalid order.~@
    :most-specific-first and :most-specific-last are the possible values."
                                         order)))
  ;; Must have a primary method
  (unless primary
    (method-combination-error "A primary method is required."))
  (make-method-call `(,@around
                      ,(make-method-call primary
                                         :operator 'and
                                         :identity-with-one-argument t))
                    :operator :call-next-method))

;The same thing, using the :order and :required keyword options
(define-method-combination and 
        (&optional (order ':most-specific-first))
        ((around (:around))
         (primary (and) :order order :required t))
  (make-method-call `(,@around
                      ,(make-method-call primary
                                         :operator 'and
                                         :identity-with-one-argument t))
                    :operator :call-next-method))

;This short-form call is behaviorally identical to the preceding
(define-method-combination and :identity-with-one-argument t)
 
;Order methods by positive integer qualifiers
;:around methods are disallowed to keep the example small
(define-method-combination example-method-combination ()
        ((methods positive-integer-qualifier-p))
  (make-method-call (stable-sort methods #'<
                       :key #'(lambda (method)
                                (first (method-qualifiers method))))))

(defun positive-integer-qualifier-p (method-qualifiers)
  (and (= (list-length method-qualifiers) 1)
       (typep (first method-qualifiers) '(integer 0 *))))

\endscreen!


\label Remarks:

The {\bf :method-combination} option of {\bf defgeneric} is used to
specify that a generic function should use a particular method
combination type.  The argument to the {\bf :method-combination}
option is the name of a method combination type.

Individual implementations might support other keyword options.
Therefore, it is required that all implementations signal an error if
they observe a keyword option that is not implemented locally.

 
\label See Also: 

{\bf make-method-call}

{\bf method-qualifiers}

{\bf method-combination-error}

{\bf invalid-method-error} 

{\bf defgeneric}

\endcom



\begincom{defmethod}\ftype{Macro}

\label Purpose:

The macro {\bf defmethod} defines a method on a generic function.  

If a generic function is currently named by the symbol {\it name\/},
the lambda-list of the method must be congruent with the lambda-list
of the generic function.  If this condition does not hold, an error is
signaled.  See the section ``Congruent Lambda-lists for All Methods of
a Generic Function'' for a definition of congruence in this context.

If {\tt (fboundp {\it name\/})} is {\bf nil}, a generic function is
created with default values for the argument precedence order (each
argument is more specific than the arguments to its right in the
argument list), for the generic function class (the class {\bf
standard-generic-function}), for the method class (the class {\bf
standard-method}), and for the method combination type (the standard
method combination type).  The lambda-list of the generic function is
congruent with the lambda-list of the method being defined.
If the symbol {\it name\/} names a non-generic function, a macro, or a
special form, an error is signaled.

The macro {\bf defmethod} may also be used to define a method on a
setf generic function.  A setf generic function is called in an
expression such as {\tt (setf ({\it name arguments\/}) new-value)}.
If {\tt (fboundp (setf {\it name\/}))} is {\bf nil},
a new setf generic function is created using the default values
described above.

\label Syntax:

\Defmac {defmethod} 
{\vtop{\hbox{\curly{name $\vert$ {\tt (setf {\it name\/})}}}
\hbox{\star{\curly{method-qualifier\/}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it method-qualifier\/}::$=$ {\it non-nil-atom}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var parameter-specializer-name\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it parameter-specializer-name\/}::$=$ {\it symbol} $\vert$ {\rm (}{\tt eql} {\it object}{\rm )}\cr
\Vskip 1pc!

\label Arguments:

The {\it name\/} argument is a non-{\bf nil} symbol that
names the generic function on which the method is defined.

If the first argument is {\tt (setf {\it name\/})}, a method is defined
on the corresponding setf generic function.

Each {\it method qualifier\/} argument is an object that is used by
method combination to identify the given method.  A method qualifier
is a non-{\bf nil} atom.  The method combination type may further
restrict what a method qualifier may be.  The standard method
combination type allows for unqualified methods or methods whose sole
qualifier is one of the following keywords: {\bf :before}, {\bf
:after}, or {\bf :around}.

The {\it specialized-lambda-list\/} argument is like an ordinary
function lambda-list except that the names of required parameters can
be replaced by specialized parameters.  A specialized parameter is a
list of the form {\tt ({\it variable-name 
parameter-specializer-name\/})}.  Only required parameters may be
specialized.  A parameter specializer name is a symbol that names a 
user-defined class, a structure defined by {\bf defstruct} if the {\bf
:type} option was not used, or a class that corresponds to a Common 
Lisp type specifier.  Note that not all Common Lisp types have a
corresponding class.  A parameter specializer name can also be {\tt
(eql {\it object\/})}.  Such a parameter specializer name indicates
that the corresponding argument must be {\bf eql} to the specified object
for the method to be applicable.  If no parameter specializer name is
specified for a given required parameter, the parameter specializer
name for that parameter defaults to {\bf t}.  A method whose required
parameters all have {\bf t} parameter specializers is termed a {\bit
default method}.  Such a method is selected when no more specific
method for the generic function is applicable.  See the section
``Introduction to Methods'' for further discussion.

For a setf generic function, the first required parameter of the
lambda list receives the {\it new-value\/} argument to {\bf setf} when
the setf method is invoked.

\label Values:

The result of {\bf defmethod} is the method object.

\label Remarks:

The class of the method object that is created is that given by the 
method class option of the generic function on which the method is defined.

If a method already exists on the given generic function with the same 
parameter specializers and the same qualifiers, {\bf defmethod} replaces
the existing method with the one now being defined. 

The parameter specializers are derived from the parameter specializer
names as described in the section ``Introduction to Methods.''

The {\bf defmethod} macro ``refers to'' each specialized parameter (see
the description of {\bf ignore} in {\it Common Lisp: The Language}, p. 160).
This includes parameters that specialize on {\bf t}.  This means that
a compiler warning does not occur if the body of the method does not refer
to a specialized parameter.  Note that a parameter that specializes on
{\bf t} is not synonymous with an unspecialized parameter in this context.

\label See Also:

{\bf add-method}

``Introduction to Methods''

``Congruent Lambda-lists for all Methods of a Generic Function'' 

\endcom


\begincom{describe}\ftype{Generic Function}

\label Purpose:

The Common Lisp function {\bf describe} is replaced by a generic
function.  The generic function {\bf describe} prints information
about a given object on the standard output.

Each implementation is required to provide a default method for {\bf
describe}, that is, a method for the class {\bf t}.  Implementations
are free to add methods for specific classes.  Users can write methods
for {\bf describe} for their own classes if they do not wish to
inherit an implementation-supplied method.  These methods must conform
to the definition of {\bf describe} as specified in {\it Common Lisp:
The Language}.

\label Syntax:

\Defgen {describe} {object}

\label Arguments:

The argument of {\bf describe} may be any Common Lisp object. 

\label Values:

The generic function {\bf describe} returns no values.

\endcom


\begincom{documentation}\ftype{Generic Function}

\label Purpose:

The Common Lisp function {\bf documentation} is replaced by a generic
function.  The generic function {\bf documentation} returns the
documentation string associated with the given object if it is
available; otherwise it returns {\bf nil}.

\label Syntax:

\Defgen documentation {x {\opt} doc-type}

\label Arguments:

The first argument is either a symbol, a list of the form {\tt (setf {\it
symbol\/})}, a method object, a class object, or a generic function
object.

If the first argument is a method object, a class object, or a generic
function object, the second argument must not be supplied.  The generic
function {\bf documentation} returns the documentation string of that object.
 
If the first argument is a symbol or a list of the form
{\tt (setf {\it symbol\/})}, the second argument must be
supplied.   The {\it doc-type\/} argument is a symbol.  It can be one
of the following types: {\bf variable}, {\bf function}, {\bf structure},
{\bf type}, {\bf setf}, and {\bf method-combination}.  The generic
function {\bf documentation} returns the documentation string of the
given type.

\beginlist

\item{\bull}
The form {\tt (documentation {\it symbol\/} 'type)} returns the documentation
string of the class object named by the symbol, if there is such a
class.   If there is no such class, it returns the documentation string
of the type specifier named by the symbol. 

\item{\bull}
The forms {\tt (documentation {\it symbol\/} 'function)} and
{\tt (documentation (setf {\it symbol\/}) 'function)} return the
documentation string of the function, generic function, special form, or
macro named by the symbol or list.

\item{\bull}
The form {\tt (documentation {\it symbol\/} 'method-combination)} returns the
documentation string of the method combination type named by the
symbol.  

\item{\bull}
The form {\tt (documentation {\it symbol\/} 'setf)} returns the documentation
string of the {\bf defsetf} or {\bf define-setf-method} associated with
the symbol.
\endlist
  
\label Values:

The documentation string associated with the given object is returned
unless none is available, in which case {\bf documentation} returns
{\bf nil}.

\vfill\eject
\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation. 

\endcom


\begincom{ensure-generic-function}\ftype{Function}

\label Purpose:

The function {\bf ensure-generic-function} is used to define a generic function
with no methods or to specify or modify options and declarations that pertain
to a generic function as a whole.

If {\it name\/} does not specify a generic function, an error is
signaled.

If {\it name\/} specifies a generic function that has different value for
any of the following arguments, the generic function is modified to
have the new value: {\bf :argument-precedence-order}, {\bf :declare},
{\bf :documentation}, {\bf :method-combination}.

If {\it name\/} specifies a generic function that has a different value for
the {\bf :lambda-list} argument, but the two values are congruent and
there are no methods, the value is changed, otherwise an error is
signaled.

If {\it name\/} specifies a generic function that has a different value for
the {\bf :generic-function-class} argument and the new generic function class
is compatible with the old, {\bf change-class} is called to change the class of
the generic function, otherwise an error is signaled.

If {\it name\/} specifies a generic function that has a different value for
the {\bf :method-class} argument, the value is changed, but any
existing methods are not changed.

\label Syntax:

\Defun {ensure-generic-function} {name\/ \key \vtop{\hbox{:lambda-list}
\hbox{:argument-precedence-order}
\hbox{:declare}
\hbox{:documentation}
\hbox{:generic-function-class}
\hbox{:method-combination}
\hbox{:method-class}
\hbox{:environment}}}

\label Arguments:

The first argument is a symbol or a list of the form {\tt (setf {\it
symbol\/})}.  In the second case, the setf generic function associated
with {\it name\/} is specified.

The keyword arguments correspond to the {\it option\/} arguments of
{\bf defgeneric}.

The {\bf :environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

\vfill\eject
\label Values:

The generic function object is returned.

%\label Remarks:

\label See Also:

{\bf defgeneric}

\endcom



\begincom{generic-flet}\ftype{Special Form}

\label Purpose:

The {\bf generic-flet} special form is an analog to the Common Lisp {\bf
flet}.  It produces new generic functions and establishes new lexical
function definition bindings.  Each generic function is created with the set
of methods specified by its method descriptions.

The special form {\bf generic-flet} is used to define functions whose
names are meaningful only locally and to execute a series of forms
with these function definition bindings.  Any number of such local
generic functions may be defined.

The names of functions defined by {\bf generic-flet} have lexical
scope; they retain their local definitions only within the body of the
{\bf generic-flet}.  Any references within the body of the {\bf
generic-flet} to functions whose names are the same as those defined
within the {\bf generic-flet} are thus references to the local
functions instead of to any global functions of the same names.  The
scope of these function definition bindings, however, includes only
the body of {\bf generic-flet}, not the definitions themselves.
Within the function definitions, local function names that match those
being defined refer to global functions defined outside the {\bf
generic-flet}.  It is thus not possible to define recursive functions
with {\bf generic-flet}.

\label Syntax:

\Defspec {generic-flet} {
\lparen{\rm$\{$}\lparen \vtop{\hbox{\curly{name lambda-list\/ $\vert$ {\tt (setf {\it name\/}) {\it setf-lambda-list}}}}
\hbox{$\lbrack\!\lbrack$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$ \rparen \star{\rm$\}$}\rparen \enskip \star\form}}}
\Vskip 1pc!
{\it name\/}::$=$ {\it symbol}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it setf-lambda-list\/}::$=$ (& {\it setf-var\/} \star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
{\it setf-var\/}::$=$ {\it var}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method {\it method-specifier\/})}
\Vskip 1pc!
{\it method-specifier\/}::$=$ \vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}}}

\label Arguments:

If the first argument is {\tt (setf {\it name\/})}, a setf generic function
is produced.

The {\it lambda-list\/}, {\it setf-lambda-list\/}, {\it option}, {\it
method-qualifier}, and {\it specialized-lambda-list\/} arguments are
the same as for {\bf defgeneric}.

Any given option may be specified at most once.

The {\it form\/} arguments are executed in order.

\label Values:

The result returned by {\bf generic-flet} is the value or values
returned by the last form executed.  If no forms are specified, 
{\bf generic-flet} returns {\bf nil}.

\label Remarks:

A {\bf generic-flet} local method definition is identical in form to the
method definition part of a {\bf defmethod}.

\label See Also:

{\bf generic-labels

defmethod

defgeneric

generic-function}

\endcom


\begincom{generic-function}\ftype{Special Form}

\label Purpose:

The {\bf generic-function} special form creates an anonymous generic
function. The generic function is created with the set of methods
specified by its method descriptions.

\label Syntax:

\Defspec {generic-function} {\vtop{\hbox{\it lambda-list}
%\hbox{\star{\curly{option $\vert$ method-description\/}}}}}
\hbox{$\lbrack\!\lbrack$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$}}}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method {\it method-specifier\/})}
\Vskip 1pc!
{\it method-specifier\/}::$=$ \vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}}}

\label Arguments:

The {\it option}, {\it method-qualifier}, and {\it
specialized-lambda-list\/} arguments are the same as for {\bf
defgeneric}.

A given option may occur only once.

\label Values:

The generic function object is returned as the result.

\label Remarks:

If no method descriptions are specified, an anonymous generic function with no
methods is created.

\vfill\eject
\label See Also:

{\bf defgeneric

generic-flet

generic-labels

defmethod}

\endcom



\begincom{generic-labels}\ftype{Special Form}

\label Purpose:

The {\bf generic-labels} special form is an analog to the Common Lisp
{\bf labels}.  It produces new generic functions and establishes new
lexical function definition bindings.  Each generic function is created
with the set of methods specified by its method descriptions.

The special form {\bf generic-labels} is used to define functions
whose names are meaningful only locally and to execute a series of
forms with these function definition bindings.  Any number of
such  local functions may be defined.  

The names of functions defined by {\bf generic-labels} have lexical
scope; they retain their local definitions only within the body of the
{\bf generic-labels} construct.  Any references within the body of the
{\bf generic-labels} construct to functions whose names are the same
as those defined within the {\bf generic-labels} form are thus
references to the local functions instead of to any global functions
of the same names.  The scope of these function definition bindings
includes the definitions themselves as well as the body of the {\bf
generic-labels} construct.

\label Syntax:

\Defspec {generic-labels} {
\lparen{\rm$\{$}\lparen \vtop{\hbox{\curly{name lambda-list\/ $\vert$ {\tt (setf {\it name\/}) {\it setf-lambda-list}}}}
\hbox{$\lbrack\!\lbrack$ option $\vert$ \star{method-description} $\rbrack\!\rbrack$ \rparen \star{\rm$\}$}\rparen \enskip \star\form}}}
\Vskip 1pc!
{\it name\/}::$=$ {\it symbol}
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it lambda-list\/}::$=$ (&\star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
\Vskip 1pc!
\settabs\+\hskip\leftskip&\cr
\+&{\it setf-lambda-list\/}::$=$ (& {\it setf-var\/} \star{\curly{var}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var\/{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var\/{\rm )}}{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} {\rm )} \cr
{\it setf-var\/}::$=$ {\it var}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method {\it method-specifier\/})}
\Vskip 1pc!
{\it method-specifier\/}::$=$ \vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}}}

\label Arguments:

If the first argument is {\tt (setf {\it name\/})}, a setf generic function
is produced.

The {\it lambda-list\/}, {\it setf-lambda-list\/}, {\it option}, {\it
method-qualifier}, and {\it specialized-lambda-list\/} arguments are
the same as for {\bf defgeneric}.

Any given option may be specified at most once.

The {\it form\/} arguments are executed in  order.

\label Values:

The result returned by {\bf generic-labels} is the value or values
returned by the last form executed.  If no forms are specified, 
{\bf generic-labels} returns {\bf nil}.

\label Remarks:

A {\bf generic-labels} local method definition is identical in form to the
method definition part of a {\bf defmethod}.

\label See Also:

{\bf generic-flet

defmethod

defgeneric

generic-function}

\endcom


\begincom{get-method}\ftype{Generic Function}

\label Purpose:

The generic function {\bf get-method} takes a generic function and returns the
method object that has the given method qualifiers
and parameter specializers.   

\label Syntax:

\Defgen {get-method} {generic-function method-qualifiers specializers {\opt} errorp}

\label Arguments:

The {\it generic-function\/} argument is a generic function.

The {\it method-qualifiers\/} argument is a list of the
method qualifiers for the method.   The order of the method qualifiers
is significant.  

The {\it specializers\/} argument is a list of the parameter
specializers for the method.  It must correspond in length to
the number of required arguments of the generic function, or
else an error is signaled.  This means that to obtain the
default method for a given generic function, a list whose
elements are the class named {\bf t} must be given.

If there is no such method and the {\it errorp\/} argument is
unsupplied or is non-{\bf nil}, {\bf get-method} signals an error.
If there is no such method and the {\it errorp\/} argument is
{\bf nil}, {\bf get-method} returns {\bf nil}.  The default value of
{\it errorp\/} is {\bf t}.

\label Values:

The result of {\bf get-method} is the method object with the given
method qualifiers and parameter specializers.

\endcom



\begincom{initialize-instance}\ftype{Generic Function}

\label Purpose:

The generic function {\bf initialize-instance} is called by {\bf
make-instance} to initialize a newly-created instance.  The function
{\bf initialize-instance} is called with the new instance, with the
initialization arguments that were supplied to {\bf make-instance},
and with any default initialization arguments.

The primary method for {\bf initialize-instance} is system-supplied.
It initializes the slots with values according to the initialization
argument list.  This default method behaves as follows on each slot,
whether shared or local:

\beginlist

\item{\bull} If an initialization argument in the defaulted initialization
argument list specifies a value for that slot, that value is stored into
the slot.  (This is true even if a {\bf :before} method has stored a value
in the slot.)

\item{\bull} Otherwise, if the slot is uninitialized and has an {\bf
:initform} form, that form is evaluated and the result is stored into the
slot.

\item{\bull} The duplicate-resolution rules mentioned in the section
``Rules for Duplication of Initialization Arguments'' are obeyed.

\endlist

\label Syntax:

\Defgen {initialize-instance} {instance \key {\tt \&allow-other-keys}}

\label Arguments:

The {\it instance\/} argument is the object to be initialized.

\label Values:

The modified instance is returned as the result.

\label Remarks:

The keyword name of each keyword parameter specifier in the lambda-list
of any method defined for {\bf initialize-instance} becomes an initialization
argument for all classes for which that method is applicable.

Methods on {\bf initialize-instance} can be defined to implement
additional initialization arguments.  These methods are typically
{\bf :after} methods, although that is not a requirement.

Implementations are permitted to optimize {\bf :initform} forms that
neither produce nor depend on side-effects, by evaluating these forms
and storing them into slots before running any {\bf
initialize-instance} methods, rather than by handling them in the primary
{\bf initialize-instance} method.  (This optimization might be
implemented by having the {\bf allocate-instance} method copy a
prototype instance.)

Implementations are permitted to optimize default value forms for
initialization arguments associated with slots by not actually
creating the complete initialization argument list when the only
method that would receive the complete list is the system-supplied
primary method.  In this case default value forms can be treated like
{\bf :initform} forms.  This optimization has no visible effects other
than a performance improvement.

\label See Also:

``Object Creation and Initialization''

{\bf make-instance

slot-boundp

slot-makunbound}

\endcom



\begincom{invalid-method-error}\ftype{Function}

\label Purpose:

The function {\bf invalid-method-error} reports an applicable method
whose qualifiers are not valid for the method combination type.  The 
error message is constructed by using a format string and any arguments to it. 
Because an implementation may need to add additional contextual information 
to the error message, {\bf invalid-method-error} should be called
only within the dynamic extent of a method-combination function.

Whether {\bf invalid-method-error} returns to its caller or exits via
{\bf throw} is implementation dependent.

\label Syntax:

\Defun {invalid-method-error} {method format-string {\rest} args}

\label Arguments:

The {\it method\/} argument is the invalid method object.  

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

The function {\bf invalid-method-error} is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
{\bf define-method-combination} form. 
A method combination function that 
imposes additional restrictions should call {\bf invalid-method-error}
explicitly if it encounters a method it cannot accept.

The function {\bf invalid-method-error} will use the
condition-signaling system when and if it is incorporated into Common Lisp.

\label See Also: 

{\bf define-method-combination}

\endcom



\begincom{make-instance}\ftype{Generic Function}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defgen {make-instance} {class \key {\it initargs}}

\label Arguments:

The {\it class\/} argument is a class object or a symbol that names a class.

The {\it initargs\/} argument is a list of alternating initialization
argument names and values.

\label Values:

The new instance is returned.

\label Remarks:

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} by using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

The meta-object protocol can be used to define new methods for {\bf
make-instance} to replace the object-creation protocol.

The {\bf make-instance} protocol may be used to create a generic function
object that is an instance of class {\bf standard-generic-function} by
supplying the following initialization arguments: {\bf :lambda-list},
{\bf :argument-precedence-order}, {\bf :declare}, {\bf :documentation},
{\bf :method-combination}, {\bf :method-class}.

\beginlist

\item{\bull}
The {\bf :lambda-list} argument is a lambda-list of the type that may be
given to {\bf defgeneric}.   

\item{\bull}
The following arguments have the same semantics as the corresponding
arguments of {\bf defgeneric}, although their syntax may differ:

\itemitem{--}
The {\bf :argument-precedence-order} argument is a list containing the
parameter names for all required arguments.  
Each required argument must be included exactly once 
so that the full and unambiguous precedence order is 
supplied.   If this condition is not met, an error is signaled.

\vfill\eject
\itemitem{--}
The {\bf :method-combination} argument is a symbol or a list.  If it
is a symbol, that symbol names a type of method combination.  If it is
a list, its first element is a symbol that names a type of method
combination, and its remaining elements are any arguments accepted by
the method combination type.  Any arguments that follow that symbol
depend on the type of method combination.  Note that the standard
method combination type does not support any arguments.  However, all
types of method combination defined by the short form of {\bf
define-method-combination} accept an optional argument named {\it
order\/}, which defaults to {\bf :most-specific-first}, where a value of {\bf
:most-specific-last} reverses the order of the primary methods
without affecting the order of the auxiliary methods.

\itemitem{--}
The {\bf :documentation} argument is a string.

\itemitem{--}
The {\bf :declare} argument is a list of declaration specifiers.

\itemitem{--}
The {\bf :method-class} argument is a class or the name of a class.
\endlist


The {\bf make-instance} protocol may be used to create a method
object that is an instance of class {\bf standard-method} by
supplying the following initialization arguments: {\bf :qualifiers},
{\bf :specializers}, {\bf :function}.

\beginlist

\item{\bull}
The {\bf :qualifiers} argument is a list of the method
qualifiers for the method.

\item{\bull}
The {\bf :specializers} argument is a list of the parameter
specializers for the method.

\item{\bull}
The {\bf :function} argument is the method function.  
The length of the list of specializers must be equal to
the number of required arguments of the method function, or
else an error is signaled.
\endlist

\label See Also:

``Object Creation and Initialization''

{\bf defclass

initialize-instance

class-of

defgeneric

defmethod}

\endcom




\begincom{make-instances-obsolete}\ftype{Generic Function}

\label Purposes:

The generic function {\bf make-instances-obsolete} is invoked automatically by
the system after {\bf defclass} has been used to redefine an existing
class.  It can also be explicitly invoked by the user.
It has the effect of initiating the process of updating the
instances of the newly-redefined class. During updating, the generic
function {\bf update-instance-structure} may be invoked.

\label Syntax:

\Defgen {make-instances-obsolete} {old-class}

\label Arguments:

The {\it old-class\/} argument is a class object or a symbol that names
the class to be redefined.

\label Values:

The modified class is returned.  The result of {\bf make-instances-obsolete}
is {\bf eq} to the {\it old-class} argument.

\label Examples: 

See the example under {\bf update-instance-structure}.

\label Remarks:

The generic function {\bf make-instances-obsolete} is invoked only on
classes that are instances of {\bf standard-class}.

\label See Also:

{\bf update-instance-structure}

``Redefining Classes''

\endcom



\begincom{make-method-call}\ftype{Function}

\label Purpose:

The function {\bf make-method-call} is used in method combination.  It
has dynamic scope within the body of a {\bf define-method-combination}
form.

The function {\bf make-method-call} returns a form whose effect is the
same as a form whose first element is the operator specified by the
{\bf :operator} keyword argument (the default is {\bf progn}) and the
rest of which is a list of forms that call the methods in the given
method list.  Each method receives the same arguments that the generic
function received.  The function {\bf make-method-call} hides the
implementation-dependent details of how methods are called.

\label Syntax:

\Defun {make-method-call} {method-list\/ {\key :operator :identity-with-one-argument}}

\label Arguments:

Each element of {\it method-list\/} can be either a method object or a list.
When a list is given, it is regarded as a form and converted when necessary
into a method whose body is that form.

If the value of {\bf :identity-with-one-argument} is true and {\it
method-list\/} contains exactly one element, the result is simply a
form that calls that single method and does not invoke the
operator.  If {\bf :operator} is {\bf progn}, the default for {\bf
:identity-with-one-argument} is true; otherwise the default for this
option is false.  This option is to be used with operators that are
identity operators when applied to one argument, that is, such
operators as {\bf progn}, {\bf and}, {\bf $+$}, and {\bf max}.  This
optimization can enable the use of an existing method as the
effective method, thus avoiding the need to create a new effective method.

If {\it method-list\/} is {\bf nil}, the result is a call to
the specified operator with no arguments or a form with the same effect.

If {\bf :operator} is {\bf :call-next-method}, the methods are
combined in a different way, rather than calling a function named
{\bf :call-next-method}.  The result is a form that calls the first method and
arranges for {\bf call-next-method} to reach the rest of the methods in the
order in which they appear in {\it method-list}.  If there is only one
method in {\it method-list}, the result is a form that calls that
method, and if the method calls {\bf call-next-method}, an error is signaled.

As a convenience, if {\it method-list\/} is a method object, it is
automatically converted to a one-element list of that method.

If {\bf call-next-method} is extended as noted, additional keyword
arguments will be needed for {\bf make-method-call}.

\eject
\label Values:

The result is a form whose effect is the same as a form whose first
element is the operator specified by the {\bf :operator} keyword
argument and the rest of which is a list of forms that call the
methods in {\it method-list}.

\label See Also: 

{\bf define-method-combination}

\endcom


\begincom{method-combination-error}\ftype{Function}

\label Purpose:

The function {\bf method-combination-error} reports a problem in
method combination.  The error message is constructed by using a format
string and any arguments to it.  Because an implementation may need to
add additional contextual information to the error message, {\bf
method-combination-error} should be called only within the dynamic
extent of a method combination function.

Whether {\bf method-combination-error} returns to its caller or exits
via {\bf throw} is implementation dependent.

\label Syntax:

\Defun {method-combination-error} {format-string {\rest} args}

\label Arguments: 

The {\it format-string\/} argument is a control string that can be
given to {\bf format}, and {\it args\/} are any arguments required by
that string.

\label Remarks:

The function {\bf method-combination-error} signals an error.

\label See Also: 

{\bf define-method-combination}

\endcom




\begincom{method-qualifiers}\ftype{Function}

\label Purpose:

The function {\bf method-qualifiers} returns a list of the qualifiers of
the given method.  

\label Syntax:

\Defun {method-qualifiers} {method}

\label Arguments:

The {\it method\/} argument is a method object. 

\label Values:

A list of the qualifiers of the given method is returned.

\label Examples:

\screen!

(setq methods (remove-duplicates methods
                                 :from-end t
                                 :key #'method-qualifiers
                                 :test #'equal))

\endscreen!

\label See Also: 

{\bf define-method-combination}

\endcom

 

\begincom{next-method-p}\ftype{Function}

\label Purpose:

The locally defined function {\bf next-method-s} is used within the body
of a method to determine whether a next method exists.

\label Syntax:

\Defun {next-method-p} {}

\label Arguments:

The function {\bf next-method-p} takes no arguments.

\label Values:

The function {\bf next-method-p} returns true or false.

\label Remarks:

Like {\bf call-next-method}, the function {\bf next-method-p} has
dynamic extent within the method within which it is referenced.
Implementations may extend {\bf next-method-p} to have indefinite
extent.  All portable programs must treat as undefined the invocation
of {\bf next-method-p} outside a generic function.



\label See Also:

{\bf call-next-method}

\endcom


\begincom{no-applicable-method}\ftype{Generic Function}

\label Purpose:

The generic function {\bf no-applicable-method} is called when a
generic function is invoked and no method of that generic function is
applicable.

The generic function {\bf no-applicable-method} is not intended to be called
by programmers.  Programmers are expected to write methods for it.

The default method on {\bf standard-generic-function} signals an
error.

\label Syntax:

\Defgen {no-applicable-method} {generic-function {\rest} function-arguments}

\label Arguments:

The {\it generic-function\/} argument of {\bf no-applicable-method} is the
generic function object of which no applicable method was found.  

The {\it function-arguments} argument is a list of the arguments to that
generic function.

\label Values:

The default method on {\bf standard-generic-function} signals an
error.

\endcom


\begincom{print-object}\ftype{Generic Function}

\label Purpose:

The generic function {\bf print-object} writes the printed
representation of an object to a stream.  The function {\bf
print-object} is called by the print system; it should not be called
by the user.

Each implementation is required to provide a default method for {\bf 
print-object}, that is, a method for the class {\bf t}.  Implementations 
are free to add methods for specific classes.  Users can write methods 
for {\bf print-object} for their own classes if they do not wish to 
inherit an implementation-supplied method. 

\label Syntax:

\Defgen {print-object} {object stream}

\label Arguments:

The first argument is any Lisp object.   The second argument is a
stream; it cannot be {\bf t} or {\bf nil}. 

\label Values:

The function {\bf print-object} returns its first argument, the object.  

\label Remarks:

Methods for {\bf print-object} must obey the print control special
variables described in {\it Common Lisp: The Language}.  The
specific details are the following:

\beginlist

\item{\bull}
Each method must implement {\bf *print-escape}*. 

\item{\bull} 
The {\bf *print-pretty*} control variable can be ignored
by most methods other than the one for lists.

\item{\bull}
The {\bf *print-circle*} control variable is handled by the printer
and can be ignored by methods.

\item{\bull}
The printer takes care of {\bf *print-level*} automatically, provided that
each method handles exactly one level of structure and
calls {\bf write} (or an equivalent function) recursively if
there are more structural levels.  The printer's decision
of whether an object has components (and therefore should
not be printed when the printing depth is not less than
{\bf *print-level*}) is implementation dependent.  In some
implementations its {\bf print-object} method is not called; in
others the method is called, and the determination that the
object has components is based on what it tries to write
to the stream.

\item{\bull}
Methods that produce output of indefinite length must obey
{\bf *print-length*}, but most methods other than the one for lists can
ignore it.

\item{\bull}
The {\bf *print-base*}, {\bf *print-radix*}, {\bf *print-case*}, {\bf
*print-gensym*}, and {\bf *print-array*} control variables apply
to specific types of objects and are handled by the methods for those
objects.

\endlist

If these rules are not obeyed, the results are undefined.

In general, the printer and the {\bf print-object} methods should not
rebind the print control variables as they operate recursively through the
structure, but this is implementation dependent.

In some implementations the stream argument passed to a {\bf
print-object} method is not the original stream, but is an
intermediate stream that implements part of the printer.  Methods
should therefore not depend on the identity of this stream.

All of the existing printing functions ({\bf write}, {\bf prin1}, {\bf
print}, {\bf princ}, {\bf pprint}, {\bf write-to-string}, {\bf
prin1-to-string}, {\bf princ-to-string}, the {\tt ~}{\bf S} and {\tt
~}{\bf A} format operations, and the {\tt ~}{\bf B}, {\tt ~}{\bf D},
{\tt ~}{\bf E}, {\tt ~}{\bf F}, {\tt ~}{\bf G}, {\tt ~}{\bf \$}, {\tt
~}{\bf O}, {\tt ~}{\bf R}, and {\tt ~}{\bf X} format operations when they
encounter a non-numeric value) are required to be changed to go
through the {\bf print-object} generic function.  Each implementation is
required to replace its former implementation of printing with one or
more {\bf print-object} methods.  Exactly which classes have methods for
{\bf print-object} is not specified; it would be valid for an implementation
to have one default method that is inherited by all system-defined
classes.

\endcom




\begincom{remove-method}\ftype{Generic Function}

\label Purpose:

The generic function {\bf remove-method} removes a method from a
generic function.  It destructively modifies the specified generic
function and returns the modified generic function as its result.

\label Syntax:

\Defgen {remove-method} {generic-function method}

\label Arguments:

The {\it generic-function\/} argument is a generic function
object.

The {\it method\/} argument is a method object.  The function {\bf
remove-method} does not signal an error if no such method is part of
the generic function.

\label Values:

The function {\bf remove-method} returns the modified generic
function.

\label See Also:

{\bf
get-method

add-method}

\endcom


\begincom{slot-boundp}\ftype{Function}

\label Purpose:

The function {\bf slot-boundp} tests whether a specific slot in an
instance is bound.

\label Syntax:

\Defun {slot-boundp} {instance slot-name}

\label Arguments:

The arguments are the instance and the name of the slot.

\label Values:

The function {\bf slot-boundp} returns true or false.

\label Remarks:

The function {\bf slot-boundp} allows for writing {\bf :after} methods for
{\bf initialize-instance} in order to initialize only slots that have not
already been initialized.

%\label See Also:

\endcom



\begincom{slot-exists-p}\ftype{Function}

\label Purpose:

The function {\bf slot-exists-p} tests whether the specified object has
a slot of the given name.

\label Syntax:

\Defun {slot-exists-p} {object slot-name}

\label Arguments:

The {\it object\/} argument is any object.  The {\it slot-name\/} argument
is a symbol.

\label Values:

The function {\bf slot-exists-p} returns true or false.

\endcom


\begincom{slot-makunbound}\ftype{Function}

\label Purpose:

The function {\bf slot-makunbound} restores a slot in an instance to
the uninitialized state.

\label Syntax:

\Defun {slot-makunbound} {instance slot-name}

\label Arguments:

The arguments to {\bf slot-makunbound} are the instance and the name of
the slot.

\label Values:

The instance is returned as the result.

%\label Remarks:

%\label See Also:

\endcom




\begincom{slot-missing}\ftype{Generic Function}

\label Purpose:

The generic function {\bf slot-missing} is invoked when an attempt is
made to access a slot in an object and the name of the slot provided
is not a name of a slot in that class.

The generic function {\bf slot-missing} is not intended to be called by
programmers.  Programmers are expected to write methods for it.

The default method on {\bf standard-class} signals an error.

\label Syntax:

\Defgen {slot-missing} {class object slot-name operation {\opt} new-value}

\label Arguments:

The required arguments to {\bf slot-missing} are the class of the object
that is being accessed, the object, the slot name, and a symbol that
indicates the operation that caused  {\bf slot-missing} to be invoked.
The optional argument to {\bf slot-missing} is used when the operation
is attempting to set the value of the slot.

\label Values:

The default method on {\bf standard-class} signals an error.

\label Remarks:

The generic function {\bf slot-missing} may be called during
evaluation of {\bf slot-value}, {\bf (setf slot-value)}), 
{\bf slot-boundp}), and {\bf slot-makunbound}.  For each
of these operations the corresponding symbol for the {\it operation\/}
argument is {\bf slot-value}, {\bf setf}, {\bf slot-boundp}, {\bf
slot-makunbound}.  

The set of arguments (including the class of the instance) facilitates
defining methods on the metaclass for {\bf slot-missing}.

\endcom


\begincom{slot-unbound}\ftype{Generic Function}

\label Purpose:

The generic function {\bf slot-unbound} is called when an
uninitialized slot is read in an instance whose meta-class is {\bf
standard-class}.

The generic function {\bf slot-unbound} is not intended to be called
by programmers.  Programmers are expected to write methods for it.
The function {\bf slot-unbound} is called only by the function
{\bf slot-value-using-class} and thus indirectly by {\bf slot-value}.

\label Syntax:

\Defgen {slot-unbound} {class instance slot-name}

\label Arguments:

The arguments to {\bf slot-unbound} are the class of the instance
whose slot was accessed, the instance itself, and the name of the
slot.

\label Values:

The method on {\bf standard-class} signals an error.

\label Remarks:

An uninitialized slot may occur if no {\bf :initform} form was
specified for the slot and the slot value has not been set, or if {\bf
slot-makunbound} has been called on the slot.

\label See Also:

{\bf slot-value-using-class

slot-makunbound}

\endcom


\begincom{slot-value}\ftype{Function}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.  If there is no slot with that
name, an error is signaled.

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot. 

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Arguments:

The arguments are the object and the name of the given slot.

\label Values:

The result is the value contained in the given slot.

\endcom



\begincom{symbol-class}\ftype{Function}

\label Purpose:

The function {\bf symbol-class} returns the class object named by
a given symbol.  If there is no class named by the given symbol,
{\bf symbol-class} returns {\bf nil}.

\label Syntax:

\Defun {symbol-class} {symbol {\opt} environment}

\label Arguments:

The first argument to {\bf symbol-class} is a symbol. 

The optional {\it environment\/} argument is the same as the {\bf
\&environment} argument to macro expansion functions.  It is typically
used to distinguish between compile-time and run-time environments.

\label Values:

The result of {\bf symbol-class} is the class object named by the given symbol.

\label Remarks:

The class associated with a particular symbol can be changed by using
{\bf setf} with {\bf symbol-class}.  The results are undefined if
the user attempts to change the class associated with a symbol that is
defined as a type specifier by {\it Common Lisp: The Language.}

\label See Also:

{\bf cboundp

cmakunbound}

\endcom


\begincom{symbol-macrolet}\ftype{Macro}

\label Purpose:

The macro {\bf symbol-macrolet} allows the substitution of forms for
variable names within a lexical scope.

\label Syntax:

\Defmac {symbol-macrolet} {\paren{\star{\paren{symbol expansion\/}}} {\body} {\it body\/}}

\label Arguments:

The {\it symbol\/} argument specifies the symbol with which the form specified
by the {\it expansion\/} argument is to be associated.

\label Values:

The result returned is that obtained by executing the forms specified
by the {\it body\/} argument.

\label Remarks:

The macro {\bf symbol-macrolet} is the basic mechanism that is used to
implement {\bf with-slots}.  This mechanism makes it possible to implement
versions of {\bf with-slots} that convert variable uses into calls to
generic function.

When the body of the {\bf symbol-macrolet} form is expanded, any use of
{\bf setq} to set the value of one of the specified variables is
converted to a use of {\bf setf}.

The symbol macro definitions are added to the macro expansion environment
within the {\bf symbol-macrolet} form.

\label See Also:

{\bf with-slots}

\endcom


\begincom{update-instance-structure}\ftype{Generic Function}

\label Purpose:

The generic function {\bf update-instance-structure} is not intended to
called by programmers. Programmers are expected to write methods for it.
The generic function {\bf update-instance-structure} is called only by
{\bf change-class}.

\label Syntax:

\Defgen {update-instance-structure} {class added-slots deleted-slots property-list}

\label Arguments:

When {\bf make-instances-obsolete} is invoked or when a class has been
redefined and an instance is being updated, a property list is created
that captures the slot names and values of all the slots with values in
the original instance.  The structure of the instance is transformed so
that it conforms to the current class definition; all the slots of this
transformed instance are uninitialized.  This transformed instance, a list
of the new slots added to the instance, a list of the old slots deleted
from the instance, and the property list containing the slot names and
values for the obsolete instance are the arguments to {\bf
update-instance-structure}.

\label Values:

The value returned by {\bf update-instance-structure} is ignored.

\label Examples:

\screen!

(defclass position () ())

(defclass x-y-position (position)
    ((x :initform 0 :accessor position-x)
     (y :initform 0 :accessor position-y)))

;;; It turns out we use polar co-ordinates more than Cartesian 
;;; co-ordinates, so we alter the representation and add some
;;; new accessor methods.

(defmethod update-instance-structure
   ((pos x-y-position) added deleted plist)
  ;; Copy the position information from old to new to make new
  ;; be a rho-theta-position at the same position as old.
  (let ((x (getf plist 'x))
        (y (getf plist 'y)))
    (setf (position-rho new) (atan y x)
          (position-theta new) (sqrt (+ (* x x) (* y y))))))

(defclass x-y-position (position)
    ((rho :initform 0 :accessor position-rho)
     (theta :initform 0 :accessor position-theta)))

;;; All instances of the old x-y-position class will be updated
;;; automatically.

;;; We give the new representation the look and feel of the old one

(defmethod position-x ((pos x-y-position))  
 (with-slots pos (rho theta) (* rho (cos theta))))

(defmethod (setf position-x) (new-x (pos x-y-position))
 (with-slots pos (rho theta)
  (let ((y (position-y pos)))
    (setq rho (atan y new-x)
          theta (sqrt (+ (* new-x new-x) (* y y))))
    new-x)))

(defmethod position-y ((pos x-y-position))
 (with-slots pos (rho theta) (* rho (sin theta))))

(defmethod (setf position-y) (new-y (pos x-y-position))
 (with-slots pos (rho theta)
  (let ((x (position-x pos)))
    (setq rho (atan new-y x)
          theta (sqrt (+ (* x x) (* new-y new-y))))
    new-y)))

\endscreen!


\label Remarks:

The default method for {\bf update-instance-structure} does the following:

\beginlist

\item{\bull} For each local slot in current class definition, if its
slot name appears in the property list, the value corresponding to the
slot name in the property list is stored in the local slot. Shared slots
are not changed.

\item{\bull} For any slot in the instance that is still uninitialized and
for which there is an {\bf :initform} form in the current class
definition, the {\bf :initform} form is evaluated and the value stored in
the local slot.

\endlist

The generic function {\bf update-instance-structure} uses standard method
combination; thus {\bf :before}, {\bf :after}, {\bf :around}, and
unqualified methods are allowed.

\label See Also:

``Redefining Classes''

{\bf make-instances-obsolete}

\endcom


\begincom{with-added-methods}\ftype{Special Form}

\label Purpose:

The {\bf with-added-methods} special form is an extension to the \OS\ {\bf
generic-labels}.  It produces new generic functions and establishes new
lexical function definition bindings.  Each generic function is created by
adding the set of methods specified by its method definitions to copies of the
methods of the lexically visible generic function of the same name.

The special form {\bf with-added-methods} is used to define functions
whose names are meaningful only locally and to execute a series of
forms with these function definition bindings.  Any number of
such local functions may be defined.  

The names of functions defined by {\bf with-added-methods} have lexical
scope; they retain their local definitions only within the body of the
{\bf with-added-methods} construct.  Any references within the body of the
{\bf with-added-methods} construct to functions whose names are the same
as those defined within the {\bf with-added-methods} form are thus
references to the local functions instead of to any global functions
of the same names.  The scope of these function definition bindings
includes the definitions themselves as well as the body of the {\bf
with-added-methods} construct.

\label Syntax:

\Defspec {with-added-methods} {
\lparen\vtop{\hbox{ \curly{name lambda-list\/ $\vert$ {\tt (setf {\it name\/})
{\it setf-lambda-list\/}}} }
\hbox{$\lbrack\!\lbrack$\thinspace option $\vert$ \star{method-description}\thinspace $\rbrack\!\rbrack$\thinspace\rparen\enspace\star\form}}}
\Vskip 1pc!
{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order
\plus{\curly{parameter-name}}) $\vert$}
\hbox{(declare \plus{\curly{declaration\/}}) $\vert$}
\hbox{(:documentation {\it string\/}) $\vert$}
\hbox{(:method-combination {\it symbol\/} \star{\curly{arg\/}}) $\vert$}
\hbox{(:generic-function-class {\it class-name\/}) $\vert$}
\hbox{(:method-class {\it class-name\/})}}}
\Vskip 1pc!
{\it method-description\/}::$=$ {\tt (:method {\it method-specifier\/})}
\Vskip 1pc!
{\it method-specifier\/}::$=$ \vtop{\hbox{\it \star{\curly{method-qualifier\/}} specialized-lambda-list\/}
\hbox{\star{\curly{declaration\/ $\vert$ documentation\/}} \star{\curly{form\/}}}}

\vfill\eject
\label Arguments:

If the first argument is {\tt (setf {\it name\/})}, a setf generic function
is produced.

The {\it option}, {\it method-qualifier}, and {\it
specialized-lambda-list\/} arguments are the same as for {\bf
defgeneric}.

Any given option may be specified at most once.

The {\it form\/} arguments are executed in  order.

\label Values:

The result returned by {\bf with-added-methods} is the value or values
returned by the last form executed.  If no forms are specified, 
{\bf with-added-methods} returns {\bf nil}.

\label Remarks:

If a generic function for {\it name\/} or {\tt (setf {\it name\/})} already
exists, the lambda-list specified in the {\bf with-added-methods} form
must be congruent with the lambda-list of that function, or else an
error is signaled.

If a generic function of the given name already exists, the {\it option\/} arguments are inherited from the existing generic function as follows:

\beginlist

\item{\bull}
If {\it name\/} specifies a generic function that has different value
for any of the following {\it option\/} arguments, the generic
function is modified to have the new value: {\bf
:argument-precedence-order}, {\bf declare}, {\bf :documentation}, {\bf
:method-combination}.

\item{\bull}
If {\it name\/} specifies a generic function that has a different
value for the {\bf :generic-function-class} {\it option\/} argument
and the new generic function class is compatible with the old, {\bf
change-class} is called to change the class of the generic function,
otherwise an error is signaled.

\item{\bull}
If {\it name\/} specifies a generic function that has a different value for
the {\bf :method-class} {\it option\/} argument, the value is changed, but any
existing methods are not changed.
\endlist

If there is no existing generic function, the {\it option\/} arguments have
the same default values as the {\it option\/} arguments to {\bf defgeneric}.

\vfill\eject
\label See Also:

{\bf generic-labels

generic-flet

defmethod

defgeneric

ensure-generic-function

generic-function}

\endcom


\begincom{with-slots}\ftype{Macro}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for referring to
specified slots as though they were variables.  Within such a context
the value of the slot can be specified by using its slot name, as if
it were a lexically bound variable.  Both {\bf setf} and {\bf setq}
can be used to set the value of the slot.  The macro {\bf with-slots}
can be used inside a method or inside any function.

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to {\bf slot-value}.

\label Syntax:  

\Defmac {with-slots} {instance-form\/ {\paren{\star{\curly{slot-entry\/}}}} {\body} body}

{\it slot-entry\/}::$=$ {\it slot-name $\vert$ {\paren{variable-name slot-name\/}}}

\label Arguments:
 
The {\it instance-form\/} argument is evaluated exactly once, upon
entry to the body of the {\bf with-slots} form.
The {\it instance-form\/} argument should evaluate to an object that has slots,
such as an instance of a user-defined class.   The {\it instance-form\/}
argument should not evaluate to an instance of a standard type class; if
it does, an error is signaled.

It is necessary that the class of the instance can be determined
lexically (at compile-time).  The {\it instance-form\/} argument must
be the name of a specialized parameter in the lambda-list of a method
that lexically contains this {\bf with-slots} form.

The {\it slot-name\/} arguments specify the slots of the instance that
can be accessed as though they were variables.  If a slot of the given
name does not exist in the instance, an error is signaled.

The form ({\tt {\it variable-name slot-name\/})} is provided to allow
the use of symbol other than the slot name for access of the slot.

\label Values:

The values of the {\bf with-slots} form are the values returned by
the last form in its body. 

\label Examples:

\screen!

(with-slots position-1
            (x y)
  (sqrt (+ (* x x)
           (* y y))))


(with-slots position-1
            ((x1 x)
             (y1 y))
  (with-slots position-2
              ((x2 x)
               (y2 y))
     (psetf x1 x2
            y1 y2))))


  (with-slots position
              (x y)
    (setq x (1+ x)
          y (1+ y)))
\endscreen!

\label Remarks:

When the body of the {\bf with-slots} form is expanded, any use of
{\bf setq} to set the value of one of the specified variables is
converted to a use of {\bf setf}.

It is legal to return lexical closures over the variables bound by
{\bf with-slots}.

An error is signaled if the class of the instance cannot be determined
from the lambda-list of a method that lexically contains the {\bf
with-slots} form or if the {\bf with-slots} form does not occur within
a method body.

An error is signaled if there is any conflict between variable names. 

\label See Also:

{\bf symbol-macrolet}

\endcom
\endChapter
\bye